// Copyright 2016 The PDFium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Original code copyright 2014 Foxit Software Inc. http://www.foxitsoftware.com

#ifndef CORE_FPDFAPI_PARSER_FPDF_PARSER_DECODE_H_
#define CORE_FPDFAPI_PARSER_FPDF_PARSER_DECODE_H_

#include <stdint.h>

#include <array>
#include <memory>
#include <optional>
#include <utility>
#include <vector>

#include "core/fxcodec/data_and_bytes_consumed.h"
#include "core/fxcrt/data_vector.h"
#include "core/fxcrt/fx_string.h"
#include "core/fxcrt/retain_ptr.h"
#include "core/fxcrt/span.h"

class CPDF_Array;
class CPDF_Dictionary;
class CPDF_Object;

namespace fxcodec {
class ScanlineDecoder;
}

// Indexed by 8-bit char code, contains unicode code points.
extern const std::array<uint16_t, 256> kPDFDocEncoding;

bool ValidateDecoderPipeline(const CPDF_Array* pDecoders);

ByteString PDF_EncodeString(ByteStringView src);
ByteString PDF_HexEncodeString(ByteStringView src);
WideString PDF_DecodeText(pdfium::span<const uint8_t> span);
ByteString PDF_EncodeText(WideStringView str);

std::unique_ptr<fxcodec::ScanlineDecoder> CreateFaxDecoder(
    pdfium::span<const uint8_t> src_span,
    int width,
    int height,
    const CPDF_Dictionary* pParams);

std::unique_ptr<fxcodec::ScanlineDecoder> CreateFlateDecoder(
    pdfium::span<const uint8_t> src_span,
    int width,
    int height,
    int nComps,
    int bpc,
    const CPDF_Dictionary* pParams);

fxcodec::DataAndBytesConsumed RunLengthDecode(
    pdfium::span<const uint8_t> src_span);

fxcodec::DataAndBytesConsumed A85Decode(pdfium::span<const uint8_t> src_span);

fxcodec::DataAndBytesConsumed HexDecode(pdfium::span<const uint8_t> src_span);

fxcodec::DataAndBytesConsumed FlateOrLZWDecode(
    bool use_lzw,
    pdfium::span<const uint8_t> src_span,
    const CPDF_Dictionary* pParams,
    uint32_t estimated_size);

// Returns std::nullopt if the filter in |pDict| is the wrong type or an
// invalid decoder pipeline.
// Returns an empty vector if there is no filter, or if the filter is an empty
// array.
// Otherwise, returns a vector of decoders.
using DecoderArray =
    std::vector<std::pair<ByteString, RetainPtr<const CPDF_Object>>>;
std::optional<DecoderArray> GetDecoderArray(
    RetainPtr<const CPDF_Dictionary> pDict);

struct PDFDataDecodeResult {
  PDFDataDecodeResult();
  PDFDataDecodeResult(DataVector<uint8_t> data,
                      ByteString image_encoding,
                      RetainPtr<const CPDF_Dictionary> image_params);
  PDFDataDecodeResult(PDFDataDecodeResult&& that) noexcept;
  PDFDataDecodeResult& operator=(PDFDataDecodeResult&& that) noexcept;
  ~PDFDataDecodeResult();

  DataVector<uint8_t> data;
  ByteString image_encoding;
  RetainPtr<const CPDF_Dictionary> image_params;
};

std::optional<PDFDataDecodeResult> PDF_DataDecode(
    pdfium::span<const uint8_t> src_span,
    uint32_t estimated_size,
    bool bImageAcc,
    const DecoderArray& decoder_array);

#endif  // CORE_FPDFAPI_PARSER_FPDF_PARSER_DECODE_H_
`fpdf_parser_decode.h` 文件定义了与 PDF 解码相关的实用功能，这些功能用于处理 PDF 文档中的各种编码格式，执行字符编码转换，创建图像解码器，以及解析解码器管道等。以下是接口功能的详细列表：

### 编码 / 解码功能

1. * *ValidateDecoderPipeline(const CPDF_Array * pDecoders) * *:
-验证解码器管道数组 `pDecoders` 的有效性。

2. * *PDF_EncodeString(ByteStringView src) * *:
-编码字符串 `src`。

3. * *PDF_HexEncodeString(ByteStringView src) * *:
-将字符串 `src` 进行十六进制编码。

4. * *PDF_DecodeText(pdfium::span<const uint8_t> span) * *:
-解码 PDF 文本为 `WideString`。

5. * *PDF_EncodeText(WideStringView str) * *:
-将宽字符串 `str` 编码为 `ByteString`。

### 解码器创建

6. * *CreateFaxDecoder(pdfium::span<const uint8_t> src_span, int width, int height, const CPDF_Dictionary * pParams) * *:
-创建一個传真扫描线解码器。

7. * *CreateFlateDecoder(pdfium::span<const uint8_t> src_span, int width, int height, int nComps, int bpc, const CPDF_Dictionary * pParams) * *:
    -创建一個 Flate 扫描线解码器。

    ### 特定解码操作

    8. * *RunLengthDecode(pdfium::span<const uint8_t> src_span) * *:
-执行运行长度解码。

9. * *A85Decode(pdfium::span<const uint8_t> src_span) * *:
    -执行 ASCII85 解码。

    10. * *HexDecode(pdfium::span<const uint8_t> src_span) * *:
    -执行十六进制解码。

    11. * *FlateOrLZWDecode(bool use_lzw, pdfium::span<const uint8_t> src_span, const CPDF_Dictionary * pParams, uint32_t estimated_size) * *:
    -根据参数选择 Flate 解码或 LZW 解码。

    ### 解码器管道处理

    12. * *GetDecoderArray(RetainPtr<const CPDF_Dictionary> pDict) * *:
-解析字典 `pDict` 中的解码器，返回解码器数组。

### 数据解码结果结构

13. * *struct PDFDataDecodeResult** :
    -用于承载解码后的数据、图像编码类型和图像参数。

    14. * *PDF_DataDecode(pdfium::span<const uint8_t> src_span, uint32_t estimated_size, bool bImageAcc, const DecoderArray & decoder_array) * *:
    -解码数据，根据提供的解码器数组，并返回解码结果。

    这些功能为 PDF 的各种数据格式提供了解码解决方案，适合用于对图像、文本等数据的解析与处理。